<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>Penlight Documentation</title>
    <link rel="stylesheet" href="../ldoc_fixed.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>Penlight</h1>

<ul>
  <li><a href="../index.html">Index</a></li>
</ul>

<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
<li><a href="#Tables">Tables</a></li>
<li><a href="#Error_handling">Error handling </a></li>
<li><a href="#File_handling">File handling </a></li>
<li><a href="#OS_functions">OS functions </a></li>
<li><a href="#String_functions">String functions </a></li>
<li><a href="#Functional">Functional </a></li>
</ul>


<h2>Libraries</h2>
<ul class="nowrap">
  <li><a href="../libraries/pl.html">pl</a></li>
  <li><a href="../libraries/pl.app.html">pl.app</a></li>
  <li><a href="../libraries/pl.array2d.html">pl.array2d</a></li>
  <li><a href="../libraries/pl.class.html">pl.class</a></li>
  <li><a href="../libraries/pl.compat.html">pl.compat</a></li>
  <li><a href="../libraries/pl.comprehension.html">pl.comprehension</a></li>
  <li><a href="../libraries/pl.config.html">pl.config</a></li>
  <li><a href="../libraries/pl.data.html">pl.data</a></li>
  <li><a href="../libraries/pl.dir.html">pl.dir</a></li>
  <li><a href="../libraries/pl.file.html">pl.file</a></li>
  <li><a href="../libraries/pl.func.html">pl.func</a></li>
  <li><a href="../libraries/pl.import_into.html">pl.import_into</a></li>
  <li><a href="../libraries/pl.input.html">pl.input</a></li>
  <li><a href="../libraries/pl.lapp.html">pl.lapp</a></li>
  <li><a href="../libraries/pl.lexer.html">pl.lexer</a></li>
  <li><a href="../libraries/pl.luabalanced.html">pl.luabalanced</a></li>
  <li><a href="../libraries/pl.operator.html">pl.operator</a></li>
  <li><a href="../libraries/pl.path.html">pl.path</a></li>
  <li><a href="../libraries/pl.permute.html">pl.permute</a></li>
  <li><a href="../libraries/pl.pretty.html">pl.pretty</a></li>
  <li><a href="../libraries/pl.seq.html">pl.seq</a></li>
  <li><a href="../libraries/pl.sip.html">pl.sip</a></li>
  <li><a href="../libraries/pl.strict.html">pl.strict</a></li>
  <li><a href="../libraries/pl.stringio.html">pl.stringio</a></li>
  <li><a href="../libraries/pl.stringx.html">pl.stringx</a></li>
  <li><a href="../libraries/pl.tablex.html">pl.tablex</a></li>
  <li><a href="../libraries/pl.template.html">pl.template</a></li>
  <li><a href="../libraries/pl.test.html">pl.test</a></li>
  <li><a href="../libraries/pl.text.html">pl.text</a></li>
  <li><a href="../libraries/pl.types.html">pl.types</a></li>
  <li><a href="../libraries/pl.url.html">pl.url</a></li>
  <li><strong>pl.utils</strong></li>
  <li><a href="../libraries/pl.xml.html">pl.xml</a></li>
</ul>
<h2>Classes</h2>
<ul class="nowrap">
  <li><a href="../classes/pl.Date.html">pl.Date</a></li>
  <li><a href="../classes/pl.List.html">pl.List</a></li>
  <li><a href="../classes/pl.Map.html">pl.Map</a></li>
  <li><a href="../classes/pl.MultiMap.html">pl.MultiMap</a></li>
  <li><a href="../classes/pl.OrderedMap.html">pl.OrderedMap</a></li>
  <li><a href="../classes/pl.Set.html">pl.Set</a></li>
</ul>
<h2>Manual</h2>
<ul class="nowrap">
  <li><a href="../manual/01-introduction.md.html">Introduction</a></li>
  <li><a href="../manual/02-arrays.md.html">Tables and Arrays</a></li>
  <li><a href="../manual/03-strings.md.html">Strings. Higher-level operations on strings.</a></li>
  <li><a href="../manual/04-paths.md.html">Paths and Directories</a></li>
  <li><a href="../manual/05-dates.md.html">Date and Time</a></li>
  <li><a href="../manual/06-data.md.html">Data</a></li>
  <li><a href="../manual/07-functional.md.html">Functional Programming</a></li>
  <li><a href="../manual/08-additional.md.html">Additional Libraries</a></li>
  <li><a href="../manual/09-discussion.md.html">Technical Choices</a></li>
</ul>
<h2>Examples</h2>
<ul class="nowrap">
  <li><a href="../examples/seesubst.lua.html">seesubst.lua</a></li>
  <li><a href="../examples/sipscan.lua.html">sipscan.lua</a></li>
  <li><a href="../examples/symbols.lua.html">symbols.lua</a></li>
  <li><a href="../examples/test-cmp.lua.html">test-cmp.lua</a></li>
  <li><a href="../examples/test-data.lua.html">test-data.lua</a></li>
  <li><a href="../examples/test-listcallbacks.lua.html">test-listcallbacks.lua</a></li>
  <li><a href="../examples/test-pretty.lua.html">test-pretty.lua</a></li>
  <li><a href="../examples/test-symbols.lua.html">test-symbols.lua</a></li>
  <li><a href="../examples/testclone.lua.html">testclone.lua</a></li>
  <li><a href="../examples/testconfig.lua.html">testconfig.lua</a></li>
  <li><a href="../examples/testglobal.lua.html">testglobal.lua</a></li>
  <li><a href="../examples/testinputfields.lua.html">testinputfields.lua</a></li>
  <li><a href="../examples/testinputfields2.lua.html">testinputfields2.lua</a></li>
  <li><a href="../examples/testxml.lua.html">testxml.lua</a></li>
  <li><a href="../examples/which.lua.html">which.lua</a></li>
</ul>

</div>

<div id="content">

<h1>Module <code>pl.utils</code></h1>
<p>Generally useful routines.</p>
<p> See  <a href="../manual/01-introduction.md.html#Generally_useful_functions_">the Guide</a>.</p>

<p> Dependencies: <a href="../libraries/pl.compat.html#">pl.compat</a>, all exported fields and functions from
 <a href="../libraries/pl.compat.html#">pl.compat</a> are also available in this module.</p>


<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#pack">pack (...)</a></td>
	<td class="summary">pack an argument list into a table.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#unpack">unpack (t[, i[, t]])</a></td>
	<td class="summary">unpack a table and return its contents.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#printf">printf (fmt, ...)</a></td>
	<td class="summary">print an arbitrary number of arguments using a format.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#fprintf">fprintf (f, fmt, ...)</a></td>
	<td class="summary">write an arbitrary number of arguments to a file using a format.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#import">import (t, T)</a></td>
	<td class="summary">take a table and 'inject' it into the local namespace.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#choose">choose (cond, value1, value2)</a></td>
	<td class="summary">return either of two values, depending on a condition.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#array_tostring">array_tostring (t[, temp[, tostr]])</a></td>
	<td class="summary">convert an array of values to strings.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#is_type">is_type (obj, tp)</a></td>
	<td class="summary">is the object of the specified type?</td>
	</tr>
</table>
<h2><a href="#Tables">Tables</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#patterns">patterns</a></td>
	<td class="summary">Some standard patterns</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#stdmt">stdmt</a></td>
	<td class="summary">Standard meta-tables as used by other Penlight modules</td>
	</tr>
</table>
<h2><a href="#Error_handling">Error handling </a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#assert_arg">assert_arg (n, val, tp, verify, msg, lev)</a></td>
	<td class="summary">assert that the given argument is in fact of the correct type.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#function_arg">function_arg (idx, f, msg)</a></td>
	<td class="summary">process a function argument.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#assert_string">assert_string (n, val)</a></td>
	<td class="summary">assert the common case that the argument is a string.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#on_error">on_error (mode)</a></td>
	<td class="summary">control the error strategy used by Penlight.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#raise">raise (err)</a></td>
	<td class="summary">used by Penlight functions to return errors.</td>
	</tr>
</table>
<h2><a href="#File_handling">File handling </a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#readfile">readfile (filename, is_bin)</a></td>
	<td class="summary">return the contents of a file as a string</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#writefile">writefile (filename, str, is_bin)</a></td>
	<td class="summary">write a string to a file</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#readlines">readlines (filename)</a></td>
	<td class="summary">return the contents of a file as a list of lines</td>
	</tr>
</table>
<h2><a href="#OS_functions">OS functions </a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#executeex">executeex (cmd, bin)</a></td>
	<td class="summary">execute a shell command and return the output.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#quote_arg">quote_arg (argument)</a></td>
	<td class="summary">Quote and escape an argument of a command.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#quit">quit ([code], msg, ...)</a></td>
	<td class="summary">error out of this program gracefully.</td>
	</tr>
</table>
<h2><a href="#String_functions">String functions </a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#escape">escape (s)</a></td>
	<td class="summary">escape any Lua 'magic' characters in a string</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#split">split (s, re, plain, n)</a></td>
	<td class="summary">split a string into a list of strings separated by a delimiter.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#splitv">splitv (s, re)</a></td>
	<td class="summary">split a string into a number of return values.</td>
	</tr>
</table>
<h2><a href="#Functional">Functional </a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#memoize">memoize (func)</a></td>
	<td class="summary">'memoize' a function (cache returned value for next call).</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#add_function_factory">add_function_factory (mt, fun)</a></td>
	<td class="summary">associate a function factory with a type.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#string_lambda">string_lambda (lf)</a></td>
	<td class="summary">an anonymous function as a string.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#bind1">bind1 (fn, p)</a></td>
	<td class="summary">bind the first argument of the function to a value.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#bind2">bind2 (fn, p)</a></td>
	<td class="summary">bind the second argument of the function to a value.</td>
	</tr>
</table>

<br/>
<br/>


    <h2 class="section-header "><a name="Functions"></a>Functions</h2>

    <dl class="function">
    <dt>
    <a name = "pack"></a>
    <strong>pack (...)</strong>
    </dt>
    <dd>
    pack an argument list into a table.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">...</span>
         any arguments
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        a table with field <code>n</code> set to the length
    </ol>


    <h3>See also:</h3>
    <ul>
         <a href="../libraries/pl.compat.html#table.pack">compat.pack</a>
    </ul>


</dd>
    <dt>
    <a name = "unpack"></a>
    <strong>unpack (t[, i[, t]])</strong>
    </dt>
    <dd>
    unpack a table and return its contents. </p>

<p> NOTE: this implementation differs from the Lua implementation in the way
 that this one DOES honor the <code>n</code> field in the table <code>t</code>, such that it is 'nil-safe'.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">t</span>
         index of the last element to unpack, defaults to <code>t.n</code> or <code>#t</code>
         (<em>optional</em>)
        </li>
        <li><span class="parameter">i</span>
         index from which to start unpacking, defaults to 1
         (<em>optional</em>)
        </li>
        <li><span class="parameter">t</span>
         index of the last element to unpack, defaults to <code>t.n</code> or <code>#t</code>
         (<em>optional</em>)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        multiple return values from the table
    </ol>


    <h3>See also:</h3>
    <ul>
         <a href="../libraries/pl.compat.html#table.unpack">compat.unpack</a>
    </ul>

    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> t = <span class="global">table</span>.pack(<span class="keyword">nil</span>, <span class="keyword">nil</span>, <span class="keyword">nil</span>, <span class="number">4</span>)
<span class="keyword">local</span> a, b, c, d = <span class="global">table</span>.<span class="global">unpack</span>(t)   <span class="comment">-- this <a href="../libraries/pl.utils.html#unpack">unpack</a> is NOT nil-safe, so d == nil
</span>
<span class="keyword">local</span> a, b, c, d = utils.<span class="global">unpack</span>(t)   <span class="comment">-- this is nil-safe, so d == 4</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "printf"></a>
    <strong>printf (fmt, ...)</strong>
    </dt>
    <dd>
    print an arbitrary number of arguments using a format.
 Output will be sent to <code>stdout</code>.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">fmt</span>
         The format (see <a href="https://www.lua.org/manual/5.1/manual.html#pdf-string.format">string.format</a>)
        </li>
        <li><span class="parameter">...</span>
         Extra arguments for format
        </li>
    </ul>





</dd>
    <dt>
    <a name = "fprintf"></a>
    <strong>fprintf (f, fmt, ...)</strong>
    </dt>
    <dd>
    write an arbitrary number of arguments to a file using a format.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">f</span>
         File handle to write to.
        </li>
        <li><span class="parameter">fmt</span>
         The format (see <a href="https://www.lua.org/manual/5.1/manual.html#pdf-string.format">string.format</a>).
        </li>
        <li><span class="parameter">...</span>
         Extra arguments for format
        </li>
    </ul>





</dd>
    <dt>
    <a name = "import"></a>
    <strong>import (t, T)</strong>
    </dt>
    <dd>
    take a table and 'inject' it into the local namespace.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">t</span>
         The table (table), or module name (string), defaults to this <a href="../libraries/pl.utils.html">utils</a> module table
        </li>
        <li><span class="parameter">T</span>
         An optional destination table (defaults to callers environment)
        </li>
    </ul>





</dd>
    <dt>
    <a name = "choose"></a>
    <strong>choose (cond, value1, value2)</strong>
    </dt>
    <dd>
    return either of two values, depending on a condition.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">cond</span>
         A condition
        </li>
        <li><span class="parameter">value1</span>
         Value returned if cond is truthy
        </li>
        <li><span class="parameter">value2</span>
         Value returned if cond is falsy
        </li>
    </ul>





</dd>
    <dt>
    <a name = "array_tostring"></a>
    <strong>array_tostring (t[, temp[, tostr]])</strong>
    </dt>
    <dd>
    convert an array of values to strings.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">t</span>
         a list-like table
        </li>
        <li><span class="parameter">temp</span>
         (table) buffer to use, otherwise allocate
         (<em>optional</em>)
        </li>
        <li><span class="parameter">tostr</span>
         custom tostring function, called with (value,index). Defaults to <a href="https://www.lua.org/manual/5.1/manual.html#pdf-tostring">tostring</a>.
         (<em>optional</em>)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        the converted buffer
    </ol>




</dd>
    <dt>
    <a name = "is_type"></a>
    <strong>is_type (obj, tp)</strong>
    </dt>
    <dd>
    is the object of the specified type?
 If the type is a string, then use type, otherwise compare with metatable


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">obj</span>
         An object to check
        </li>
        <li><span class="parameter">tp</span>
         String of what type it should be
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        boolean
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example">utils.is_type(<span class="string">"hello world"</span>, <span class="string">"string"</span>)   <span class="comment">--&gt; true
</span><span class="comment">-- or check metatable
</span><span class="keyword">local</span> my_mt = {}
<span class="keyword">local</span> my_obj = <span class="global">setmetatable</span>(my_obj, my_mt)
utils.is_type(my_obj, my_mt)  <span class="comment">--&gt; true</span></pre>
    </ul>

</dd>
</dl>
    <h2 class="section-header "><a name="Tables"></a>Tables</h2>

    <dl class="function">
    <dt>
    <a name = "patterns"></a>
    <strong>patterns</strong>
    </dt>
    <dd>
    Some standard patterns


    <h3>Fields:</h3>
    <ul>
        <li><span class="parameter">FLOAT</span>
        floating point number
        </li>
        <li><span class="parameter">INTEGER</span>
        integer number
        </li>
        <li><span class="parameter">IDEN</span>
        identifier
        </li>
        <li><span class="parameter">FILE</span>
        file
        </li>
    </ul>





</dd>
    <dt>
    <a name = "stdmt"></a>
    <strong>stdmt</strong>
    </dt>
    <dd>
    Standard meta-tables as used by other Penlight modules


    <h3>Fields:</h3>
    <ul>
        <li><span class="parameter">List</span>
         the List metatable
        </li>
        <li><span class="parameter">Map</span>
         the Map metatable
        </li>
        <li><span class="parameter">Set</span>
         the Set metatable
        </li>
        <li><span class="parameter">MultiMap</span>
         the MultiMap metatable
        </li>
    </ul>





</dd>
</dl>
    <h2 class="section-header "><a name="Error_handling"></a>Error handling </h2>

    <dl class="function">
    <dt>
    <a name = "assert_arg"></a>
    <strong>assert_arg (n, val, tp, verify, msg, lev)</strong>
    </dt>
    <dd>
    assert that the given argument is in fact of the correct type.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">n</span>
         argument index
        </li>
        <li><span class="parameter">val</span>
         the value
        </li>
        <li><span class="parameter">tp</span>
         the type
        </li>
        <li><span class="parameter">verify</span>
         an optional verification function
        </li>
        <li><span class="parameter">msg</span>
         an optional custom message
        </li>
        <li><span class="parameter">lev</span>
         optional stack position for trace, default 2
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        the validated value
    </ol>

    <h3>Raises:</h3>
    if <code>val</code> is not the correct type


    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> param1 = assert_arg(<span class="number">1</span>,<span class="string">"hello"</span>,<span class="string">'table'</span>)  <span class="comment">--&gt; error: argument 1 expected a 'table', got a 'string'
</span><span class="keyword">local</span> param4 = assert_arg(<span class="number">4</span>,<span class="string">'!@#$%^&amp;*'</span>,<span class="string">'string'</span>,path.isdir,<span class="string">'not a directory'</span>)
     <span class="comment">--&gt; error: argument 4: '!@#$%^&amp;*' not a directory</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "function_arg"></a>
    <strong>function_arg (idx, f, msg)</strong>
    </dt>
    <dd>
    process a function argument.
 This is used throughout Penlight and defines what is meant by a function:
 Something that is callable, or an operator string as defined by <code>pl.operator</code>,
 such as '>' or '#'. If a function factory has been registered for the type, it will
 be called to get the function.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">idx</span>
         argument index
        </li>
        <li><span class="parameter">f</span>
         a function, operator string, or callable object
        </li>
        <li><span class="parameter">msg</span>
         optional error message
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        a callable
    </ol>

    <h3>Raises:</h3>
    if idx is not a number or if f is not callable



</dd>
    <dt>
    <a name = "assert_string"></a>
    <strong>assert_string (n, val)</strong>
    </dt>
    <dd>
    assert the common case that the argument is a string.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">n</span>
         argument index
        </li>
        <li><span class="parameter">val</span>
         a value that must be a string
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        the validated value
    </ol>

    <h3>Raises:</h3>
    val must be a string


    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> val = <span class="number">42</span>
<span class="keyword">local</span> param2 = utils.assert_string(<span class="number">2</span>, val) <span class="comment">--&gt; error: argument 2 expected a 'string', got a 'number'</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "on_error"></a>
    <strong>on_error (mode)</strong>
    </dt>
    <dd>

<p>control the error strategy used by Penlight.
 This is a global setting that controls how <a href="../libraries/pl.utils.html#raise">utils.raise</a> behaves:</p>

<ul>
    <li>'default': return <code>nil + error</code> (this is the default)</li>
    <li>'error': throw a Lua error</li>
    <li>'quit': exit the program</li>
</ul>




    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">mode</span>
         either 'default', 'quit'  or 'error'
        </li>
    </ul>



    <h3>See also:</h3>
    <ul>
         <a href="../libraries/pl.utils.html#raise">utils.raise</a>
    </ul>


</dd>
    <dt>
    <a name = "raise"></a>
    <strong>raise (err)</strong>
    </dt>
    <dd>
    used by Penlight functions to return errors.  Its global behaviour is controlled
 by <a href="../libraries/pl.utils.html#on_error">utils.on_error</a>.
 To use this function you MUST use it in conjunction with <code>return</code>, since it might
 return <code>nil + error</code>.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">err</span>
         the error string.
        </li>
    </ul>



    <h3>See also:</h3>
    <ul>
         <a href="../libraries/pl.utils.html#on_error">utils.on_error</a>
    </ul>

    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">if</span> some_condition <span class="keyword">then</span>
  <span class="keyword">return</span> utils.raise(<span class="string">"some condition was not met"</span>)  <span class="comment">-- MUST use 'return'!
</span><span class="keyword">end</span></pre>
    </ul>

</dd>
</dl>
    <h2 class="section-header "><a name="File_handling"></a>File handling </h2>

    <dl class="function">
    <dt>
    <a name = "readfile"></a>
    <strong>readfile (filename, is_bin)</strong>
    </dt>
    <dd>
    return the contents of a file as a string


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">filename</span>
         The file path
        </li>
        <li><span class="parameter">is_bin</span>
         open in binary mode
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        file contents
    </ol>




</dd>
    <dt>
    <a name = "writefile"></a>
    <strong>writefile (filename, str, is_bin)</strong>
    </dt>
    <dd>
    write a string to a file


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">filename</span>
         The file path
        </li>
        <li><span class="parameter">str</span>
         The string
        </li>
        <li><span class="parameter">is_bin</span>
         open in binary mode
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>
        <li>
        true or nil</li>
        <li>
        error message</li>
    </ol>

    <h3>Raises:</h3>
    error if filename or str aren't strings



</dd>
    <dt>
    <a name = "readlines"></a>
    <strong>readlines (filename)</strong>
    </dt>
    <dd>
    return the contents of a file as a list of lines


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">filename</span>
         The file path
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        file contents as a table
    </ol>

    <h3>Raises:</h3>
    error if filename is not a string



</dd>
</dl>
    <h2 class="section-header "><a name="OS_functions"></a>OS functions </h2>

    <dl class="function">
    <dt>
    <a name = "executeex"></a>
    <strong>executeex (cmd, bin)</strong>
    </dt>
    <dd>
    execute a shell command and return the output.
 This function redirects the output to tempfiles and returns the content of those files.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">cmd</span>
         a shell command
        </li>
        <li><span class="parameter">bin</span>
         boolean, if true, read output as binary file
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>
        <li>
        true if successful</li>
        <li>
        actual return code</li>
        <li>
        stdout output (string)</li>
        <li>
        errout output (string)</li>
    </ol>




</dd>
    <dt>
    <a name = "quote_arg"></a>
    <strong>quote_arg (argument)</strong>
    </dt>
    <dd>
    Quote and escape an argument of a command.
 Quotes a single (or list of) argument(s) of a command to be passed
 to <a href="https://www.lua.org/manual/5.1/manual.html#pdf-os.execute">os.execute</a>, <code>pl.utils.execute</code> or <a href="../libraries/pl.utils.html#executeex">pl.utils.executeex</a>.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">argument</span>
         (string or table/list) the argument to quote. If a list then
 all arguments in the list will be returned as a single string quoted.
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        quoted and escaped argument.
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> options = utils.quote_arg {
    <span class="string">"-lluacov"</span>,
    <span class="string">"-e"</span>,
    <span class="string">"utils = print(require('pl.utils')._VERSION"</span>,
}
<span class="comment">-- returns: -lluacov -e 'utils = print(require('\''pl.utils'\'')._VERSION'</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "quit"></a>
    <strong>quit ([code], msg, ...)</strong>
    </dt>
    <dd>
    error out of this program gracefully.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">code</span>
         The exit code, defaults to -<code>1</code> if omitted
         (<em>optional</em>)
        </li>
        <li><span class="parameter">msg</span>
         The exit message will be sent to <code>stderr</code> (will be formatted with the extra parameters)
        </li>
        <li><span class="parameter">...</span>
         extra arguments for message's format'
        </li>
    </ul>



    <h3>See also:</h3>
    <ul>
         <a href="../libraries/pl.utils.html#fprintf">utils.fprintf</a>
    </ul>

    <h3>Usage:</h3>
    <ul>
        <pre class="example">utils.quit(-<span class="number">1</span>, <span class="string">"Error '%s' happened"</span>, <span class="string">"42"</span>)
<span class="comment">-- is equivalent to
</span>utils.quit(<span class="string">"Error '%s' happened"</span>, <span class="string">"42"</span>)  <span class="comment">--&gt; Error '42' happened</span></pre>
    </ul>

</dd>
</dl>
    <h2 class="section-header "><a name="String_functions"></a>String functions </h2>

    <dl class="function">
    <dt>
    <a name = "escape"></a>
    <strong>escape (s)</strong>
    </dt>
    <dd>
    escape any Lua 'magic' characters in a string


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">s</span>
         The input string
        </li>
    </ul>





</dd>
    <dt>
    <a name = "split"></a>
    <strong>split (s, re, plain, n)</strong>
    </dt>
    <dd>
    split a string into a list of strings separated by a delimiter.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">s</span>
         The input string
        </li>
        <li><span class="parameter">re</span>
         A Lua string pattern; defaults to '%s+'
        </li>
        <li><span class="parameter">plain</span>
         don't use Lua patterns
        </li>
        <li><span class="parameter">n</span>
         optional maximum number of splits
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        a list-like table
    </ol>

    <h3>Raises:</h3>
    error if s is not a string



</dd>
    <dt>
    <a name = "splitv"></a>
    <strong>splitv (s, re)</strong>
    </dt>
    <dd>
    split a string into a number of return values.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">s</span>
         the string
        </li>
        <li><span class="parameter">re</span>
         the delimiter, default space
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        n values
    </ol>


    <h3>See also:</h3>
    <ul>
         <a href="../libraries/pl.utils.html#split">split</a>
    </ul>

    <h3>Usage:</h3>
    <ul>
        <pre class="example">first,<span class="global">next</span> = splitv(<span class="string">'jane:doe'</span>,<span class="string">':'</span>)</pre>
    </ul>

</dd>
</dl>
    <h2 class="section-header "><a name="Functional"></a>Functional </h2>

    <dl class="function">
    <dt>
    <a name = "memoize"></a>
    <strong>memoize (func)</strong>
    </dt>
    <dd>
    'memoize' a function (cache returned value for next call).
 This is useful if you have a function which is relatively expensive,
 but you don't know in advance what values will be required, so
 building a table upfront is wasteful/impossible.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">func</span>
         a function of at least one argument
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        a function with at least one argument, which is used as the key.
    </ol>




</dd>
    <dt>
    <a name = "add_function_factory"></a>
    <strong>add_function_factory (mt, fun)</strong>
    </dt>
    <dd>
    associate a function factory with a type.
 A function factory takes an object of the given type and
 returns a function for evaluating it


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">mt</span>
            <span class="types"><span class="type">tab</span></span>
         metatable
        </li>
        <li><span class="parameter">fun</span>
            <span class="types"><span class="type">func</span></span>
         a callable that returns a function
        </li>
    </ul>





</dd>
    <dt>
    <a name = "string_lambda"></a>
    <strong>string_lambda (lf)</strong>
    </dt>
    <dd>
    an anonymous function as a string.  This string is either of the form
 '|args| expression' or is a function of one argument, '_'


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">lf</span>
         function as a string
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        a function
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example">string_lambda <span class="string">'|x|x+1'</span> (<span class="number">2</span>) == <span class="number">3</span>
string_lambda <span class="string">'_+1'</span> (<span class="number">2</span>) == <span class="number">3</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "bind1"></a>
    <strong>bind1 (fn, p)</strong>
    </dt>
    <dd>
    bind the first argument of the function to a value.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">fn</span>
         a function of at least two values (may be an operator string)
        </li>
        <li><span class="parameter">p</span>
         a value
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        a function such that f(x) is fn(p,x)
    </ol>

    <h3>Raises:</h3>
    same as <a href="../libraries/pl.utils.html#function_arg">function_arg</a>

    <h3>See also:</h3>
    <ul>
         <a href="../libraries/pl.func.html#bind1">func.bind1</a>
    </ul>

    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> <span class="keyword">function</span> f(msg, name)
  <span class="global">print</span>(msg .. <span class="string">" "</span> .. name)
<span class="keyword">end</span>

<span class="keyword">local</span> hello = utils.bind1(f, <span class="string">"Hello"</span>)

<span class="global">print</span>(hello(<span class="string">"world"</span>))     <span class="comment">--&gt; "Hello world"
</span><span class="global">print</span>(hello(<span class="string">"sunshine"</span>))  <span class="comment">--&gt; "Hello sunshine"</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "bind2"></a>
    <strong>bind2 (fn, p)</strong>
    </dt>
    <dd>
    bind the second argument of the function to a value.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">fn</span>
         a function of at least two values (may be an operator string)
        </li>
        <li><span class="parameter">p</span>
         a value
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        a function such that f(x) is fn(x,p)
    </ol>

    <h3>Raises:</h3>
    same as <a href="../libraries/pl.utils.html#function_arg">function_arg</a>


    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> <span class="keyword">function</span> f(a, b, c)
  <span class="global">print</span>(a .. <span class="string">" "</span> .. b .. <span class="string">" "</span> .. c)
<span class="keyword">end</span>

<span class="keyword">local</span> hello = utils.bind1(f, <span class="string">"world"</span>)

<span class="global">print</span>(hello(<span class="string">"Hello"</span>, <span class="string">"!"</span>))  <span class="comment">--&gt; "Hello world !"
</span><span class="global">print</span>(hello(<span class="string">"Bye"</span>, <span class="string">"?"</span>))    <span class="comment">--&gt; "Bye world ?"</span></pre>
    </ul>

</dd>
</dl>


</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2019-10-14 15:29:36 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
